IN LIST: add UInt8 bitmap filter#23011
Merged
Merged
Conversation
10 tasks
geoffreyclaude
force-pushed
the
perf/in_list_bitmap_u8_filter
branch
from
b865b12 to
b910c6a
Compare
This was referenced Jun 18, 2026
geoffreyclaude
changed the title
geoffreyclaude
force-pushed
the
perf/in_list_bitmap_u8_filter
branch
2 times, most recently
from
80597b1 to
2f19956
Compare
geoffreyclaude
force-pushed
the
perf/in_list_bitmap_u8_filter
branch
2 times, most recently
from
5351b95 to
acfc578
Compare
Contributor
|
run benchmark in_list_strategy |
Contributor
|
run benchmarks |
Contributor
|
@geoffreyclaude mind fixing failing ci? |
|
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_bitmap_u8_filter (acfc578) to d2d9b12 (merge-base) diff using: in_list_strategy File an issue against this benchmark runner |
|
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_bitmap_u8_filter (acfc578) to d2d9b12 (merge-base) diff using: clickbench_partitioned File an issue against this benchmark runner |
|
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_bitmap_u8_filter (acfc578) to d2d9b12 (merge-base) diff using: tpcds File an issue against this benchmark runner |
|
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_bitmap_u8_filter (acfc578) to d2d9b12 (merge-base) diff using: tpch File an issue against this benchmark runner |
Dandandan
reviewed
Jun 22, 2026
| exec_datafusion_err!("UInt8BitmapFilter: expected UInt8 array") | ||
| })?; | ||
| let mut bits = [0u64; 4]; | ||
| for v in prim_array.iter().flatten() { |
Contributor
There was a problem hiding this comment.
prim_array.iter().flatten()generally is slower than iterating over.values()(when no nulls). (Also for nulls I think it is probably faster to include the nulls into thebits[index / 64] |=calculation.
Contributor
Author
There was a problem hiding this comment.
Done in new commit on this PR
|
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)Details
Resource Usagetpch — base (merge-base)
tpch — branch
File an issue against this benchmark runner |
|
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)Details
Resource Usagetpcds — base (merge-base)
tpcds — branch
File an issue against this benchmark runner |
Contributor
Author
@adriangb Unfortunately it's completely unrelated to my change: |
|
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)Details
Resource Usageclickbench_partitioned — base (merge-base)
clickbench_partitioned — branch
File an issue against this benchmark runner |
Contributor
I retriggered it |
Replaces HashSet<u8> with a 32-byte stack-allocated bitmap. Provides O(1) membership testing via bit-shifting, significantly reducing memory overhead and improving cache locality. Triggers for UInt8 arrays.
geoffreyclaude
force-pushed
the
perf/in_list_bitmap_u8_filter
branch
from
acfc578 to
3bf986a
Compare
|
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)Details
Resource Usagein_list_strategy — base (merge-base)
in_list_strategy — branch
File an issue against this benchmark runner |
geoffreyclaude
force-pushed
the
perf/in_list_bitmap_u8_filter
branch
from
3bf986a to
2ee4eab
Compare
geoffreyclaude
commented
Jun 22, 2026
| let values = prim_array.values(); | ||
| match prim_array.nulls() { | ||
| None => { | ||
| for &v in values { |
Contributor
Author
There was a problem hiding this comment.
values.iter().copied().for_each(set_bit) is shorter, but less legible. Both should compile the same.
Contributor
Author
|
run benchmark in_list_strategy |
|
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_bitmap_u8_filter (2ee4eab) to 60c407c (merge-base) diff using: in_list_strategy File an issue against this benchmark runner |
|
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)Details
Resource Usagein_list_strategy — base (merge-base)
in_list_strategy — branch
File an issue against this benchmark runner |
alamb
approved these changes
Jun 23, 2026
alamb
left a comment
alamb
left a comment
Contributor
There was a problem hiding this comment.
Thank you @geoffreyclaude and @Dandandan -- this looks good to me
| #[inline(always)] | ||
| fn check(&self, needle: u8) -> bool { | ||
| let index = needle as usize; | ||
| (self.bits[index / 64] >> (index % 64)) & 1 != 0 |
Contributor
There was a problem hiding this comment.
It would be interesting to know of llvm could optimize the bounds check here (it knows that index <= 256 so index / 64 is always in bounds
Contributor
Author
There was a problem hiding this comment.
Confirmed (with some Codex help): rustc/LLVM does optimize this bounds check away in optimized builds.
Godbolt repro: https://godbolt.org/z/6r1WjvYv4
I used LLVM IR there because retained Rust bounds checks are easy to spot: they show up as a branch to a panic block calling panic_bounds_check.
For the u8 versions (bitmap_check / bitmap_set), there is no such branch. The IR widens the u8 with:
%index = zext i8 %needle to i64then computes index / 64 as a shift and directly loads/stores from the [u64; 4].
For contrast, the repro also includes the same expression with index: usize; that version does emit:
icmp ult i64 %index, 256
br i1 ..., label %bb1, label %panicfollowed by panic_bounds_check.
So I think the safe indexing here already compiles to the unchecked access we want on the hot path, without needing get_unchecked.
Contributor
|
I'll plan to merge this tomorrow unless anyone else would like more time to review Thank you (again) for your patience @geoffreyclaude |
adriangb
pushed a commit
to pydantic/datafusion
that referenced
this pull request
Jun 26, 2026
## Which issue does this PR close? - Part of apache#19241. - Stacked on apache#23011. - Next in stack: apache#23035. - Extracted from apache#19390. ## Rationale for this change apache#23011 uses a bitmap checklist for `UInt8`, where there are 256 possible values. `UInt16` is the same idea with a larger value range: 0 through 65,535. That is still small enough to represent directly. A `UInt16` bitmap needs one bit for each possible value: - 65,536 possible values - 65,536 bits total - 8 KB of memory Then a lookup is still simple: use the input value as the bit position and check whether that bit is set. For example, if the list contains `42`, bit `42` is set, and every input row with value `42` can be recognized with one bit test. This PR keeps the scope narrow: it adds the unsigned 2-byte bitmap path as a concrete `UInt16` filter. apache#23035 then unifies the `UInt8` and `UInt16` implementations, and apache#23013 uses that shared shape for signed same-width reinterpretation. ## What changes are included in this PR? - Adds `UInt16BitmapFilter`, backed by a heap-allocated 65,536-bit bitmap. - Routes `UInt16` constant-list filtering to that bitmap path. - Keeps the same `IN` / `NOT IN` null behavior as the generic path. - Adds focused coverage for `UInt16` boundary values, nulls, and `NOT IN`. ## Are these changes tested? Yes. - `cargo fmt --all` - `cargo test -p datafusion-physical-expr bitmap_filter_u16 --lib` - `cargo test -p datafusion-physical-expr in_list_int_types --lib` - `cargo test -p datafusion-physical-expr test_in_list_from_array_type_combinations --lib` - `cargo test -p datafusion-physical-expr test_in_list_dictionary_types --lib` - `cargo clippy -p datafusion-physical-expr --all-targets --all-features -- -D warnings` ## Are there any user-facing changes? No. This is an internal performance optimization only. <!-- codex-benchmark-start --> ## Benchmark note No local `in_list_strategy` numbers are included for this PR because the benchmark harness does not currently include a direct `UInt16` case. The available `i16` rows measure the signed reinterpretation path added in apache#23013 after the bitmap unification in apache#23035, not this PR's unsigned `UInt16` bitmap filter. <!-- codex-benchmark-end -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
INperformance with specialized implementations #19390.Rationale for this change
IN LISTevaluates expressions likex IN (1, 3, 7). The list on the right is fixed, so DataFusion can precompute a small lookup structure once and then reuse it for every input row.For
UInt8, there are only 256 possible values: 0 through 255. That means the lookup can be a tiny checklist with one bit per possible value:3, set bit3.7, set bit7.So instead of hashing each input value or comparing it against the list, membership becomes one indexed bit test. The bitmap is only 32 bytes, because 256 bits = 32 bytes.
This PR adds the first specialized primitive path in the stack as a concrete
UInt8filter. TheUInt16version is added in #23012, and the shared bitmap abstraction is introduced only after both concrete implementations are visible in #23035.What changes are included in this PR?
UInt8BitmapFilter, a 32-byte bitmap built from the non-null constants in theINlist.UInt8constant-list filtering to that bitmap path.INandNOT IN.static_filter.rs, so specialized filters can reuse it consistently.UInt8null handling and dictionary-encoded needles.Are these changes tested?
Yes.
cargo fmt --allcargo test -p datafusion-physical-expr bitmap_filter_u8 --libcargo test -p datafusion-physical-expr in_list_int_types --libcargo clippy -p datafusion-physical-expr --all-targets --all-features -- -D warningsAre there any user-facing changes?
No. This is an internal performance optimization only.
Local benchmark snapshot
Benchmark command:
Method: compare adjacent saved baselines using raw Criterion sample minima (
min(time / iters)). Lower is better; changes within +/-5% are treated as noise. These numbers were not rerun after splitting the bitmap abstraction into #23035.Compared baselines: #21927 -> #23011
Relevant scope: UInt8 narrow-integer rows.
Summary: 5 relevant rows, 5 faster, 0 slower, 0 within +/-5%.
narrow_integer/u8/list=16/match=0%narrow_integer/u8/list=16/match=50%narrow_integer/u8/list=4/match=0%narrow_integer/u8/list=4/match=50%nulls/narrow_integer/u8/list=16/match=50%/nulls=20%